<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">















 
 
 
 
 
 
 
  
  


<html>
  <head>
    <script type="text/javascript" language="JavaScript">
    ORIGINAL_PAGE_PATH = "/appengine/docs/java/datastore/dataclasses.html";
    </script>
    
    
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Defining Data Classes - Google App Engine - Google Code</title>
<script type="text/javascript"><!--
(function(){function a(){this.t={};this.tick=function(c){this.t[c]=(new Date).getTime()};this.tick("start")}var b=new a;window.jstiming={Timer:a,load:b};if(window.external&&window.external.pageT)window.jstiming.pt=window.external.pageT;})();

var _tocPath_ = '/appengine/docs/_toc.ezt';
var codesite_token = null;
//--></script>
<link href="../../../../css/codesite.pack.04102009.css" type="text/css" rel="stylesheet"></link>
<script src="../../../../js/codesite_head.pack.04102009.js" type="text/javascript"></script>
<script type="text/javascript">CODESITE_CSITimer['load'].tick('bhs');</script>
<link rel="search" type="application/opensearchdescription+xml" title="Google Code" href="http://code.google.com/osd.xml" />

<!--[if IE]><link rel="stylesheet" type="text/css" href="../../../../css/iehacks.css" /><![endif]-->

    <link href="../../../../css/semantic_headers.css" rel="stylesheet" type="text/css" />
    <link href="../../../css/local_extensions.css" rel="stylesheet" type="text/css" />
  </head>

  <body class="gc-documentation">

    
    
    
</a>

<div id="gb">
 <span>
  
    <a id="lang-dropdown" class="dropdown" href="http://code.google.com" onclick="return false;"><img class="globeicon" src="../../../../images/globe2_small.png"/><span>English</span></a>
  
 </span>
</div>

<div class="gbh" style="left: 0pt;"></div>
<div class="gbh" style="right: 0pt;"></div>


<style type="text/css">
  #gc-topnav h1 {
    padding: 0 0 0 6px;
  }
</style>


<div id="gc-container">
<a name="top"></a>
<div id="skipto">
  <a href="#gc-pagecontent">Skip to page content</a>
  <a href="#gc-toc">Skip to main navigation</a>
</div>

<div id="gc-header">
  <div id="logo"><a href="http://code.google.com">
  
  
     <img src="../../../../images/cleardot.gif" height="1px" width="1px" alt="Google Code Home Page" id="gc-logo-img"/>
  
  
  </a></div>
  <div id="search">
    <div id="searchForm" class="searchForm">
      <form id="cse" action="http://www.google.com/cse" accept-charset="utf-8" class="gsc-search-box" onsubmit="executeGSearch(document.getElementById('gsearchInput').value); return false;">
      <noscript>
      <input type="hidden" name="cref" value="http://code.google.com/cse/googlecode-context.xml"/>
      </noscript>
        <table class="gsc-search-box" cellpadding="0" cellspacing="0">
          <tbody>
            <tr>
              <td class="gsc-input">
                <input id="gsearchInput" type="text" name="q" maxlength="2048" class="gsc-input" autocomplete="off" title="Google Code Search" style="width:345px"/>
              </td>
              <td class="gsc-search-button">
                <div id="cs-searchresults" onclick="event.cancelBubble = true;"></div>
                <input title="Search" id="gsearchButton" class="gsc-search-button" name="sa" value="Search" type="submit"/>
              </td>
            </tr>
            <tr>
              <td colspan="2" class="greytext">e.g. "templates" or "datastore"</td>
            </tr>
          </tbody>
        </table>
      </form>
    </div> <!-- end searchForm -->
  </div> <!-- end search -->
</div> <!-- end gc-header -->


<div id="codesiteContent">

<a name="gc-topnav-anchor"></a>
<div id="gc-topnav">
  <h1>Google App Engine</h1>
  <ul id="docs" class="gc-topnav-tabs">

    <li id="home_link">
      <a href="../../../index.html" title="Google App Engine home page">Home</a>
    </li>
  
    <li id="docs_link">
      <a href="../../index.html" class="selected" title="Official Google App Engine documentation">Docs</a>
    </li>
  
    <li id="faq_link">
      <a href="../../../kb/index.html" title="Answers to frequently asked questions about Google App Engine">FAQ</a>
    </li>
  
    <li id="articles_link">
      <a href="../../../articles/index.html" title="Focused articles and tutorials for Google App Engine developers">Articles</a>
    </li>
  
    <li>
      <a href="http://googleappengine.blogspot.com/" title="Official Google App Engine blog">Blog</a>
    </li>
  
    <li>
      <a href="../../../community.html" title="Community home for Google App Engine">Community</a>
    </li>
  
    <li>
      <a href="../../../terms.html" title="Google App Engine terms of service">Terms</a>
    </li>
  
    <li>
      <a href="../../../downloads.html" title="Download Google App Engine">Download</a>
    </li>
  

  </ul>
</div> <!-- end gc-topnav -->

    <div class="g-section g-tpl-170">

      <div class="g-unit g-first" id="gc-toc">
        <ul>
  <li><a href="../../../downloads.html">Downloads</a></li>
  <li><a href="http://code.google.com/status/appengine">System Status</a></li>
  <li><a href="http://code.google.com/p/googleappengine/issues/list">Issue Tracker</a></li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Getting Started</h2>
    <ul>
      <li><a href="../../whatisgoogleappengine.html">What Is Google App Engine?</a></li>
      <li><a href="../gettingstarted/index.html">Java</a>
        <ul>
              <li><a href="../gettingstarted/introduction.html">Introduction</a></li>
    <li><a href="../gettingstarted/installing.html">Installing the Java SDK</a></li>
    <li><a href="../gettingstarted/creating.html">Creating a Project</a></li>
    <li><a href="../gettingstarted/usingusers.html">Using the Users Service</a></li>
    <li><a href="../gettingstarted/usingjsps.html">Using JSPs</a></li>
    <li><a href="../gettingstarted/usingdatastore.html">Using the Datastore with JDO</a></li>
    <li><a href="../gettingstarted/staticfiles.html">Using Static Files</a></li>
    <li><a href="../gettingstarted/uploading.html">Uploading Your Application</a></li>

        </ul>
      </li>
      <li><a href="../../python/gettingstarted/index.html">Python</a>
        <ul>
            <li><a href="../../python/gettingstarted/introduction.html">Introduction</a></li>
  <li><a href="../../python/gettingstarted/devenvironment.html">The Development Environment</a></li>
  <li><a href="../../python/gettingstarted/helloworld.html">Hello, World!</a></li>
  <li><a href="../../python/gettingstarted/usingwebapp.html">Using the webapp Framework</a></li>
  <li><a href="../../python/gettingstarted/usingusers.html">Using the Users Service</a></li>
  <li><a href="../../python/gettingstarted/handlingforms.html">Handling Forms With webapp</a></li>
  <li><a href="../../python/gettingstarted/usingdatastore.html">Using the Datastore</a></li>
  <li><a href="../../python/gettingstarted/templates.html">Using Templates</a></li>
  <li><a href="../../python/gettingstarted/staticfiles.html">Using Static Files</a></li>
  <li><a href="../../python/gettingstarted/uploading.html">Uploading Your Application</a></li>

        </ul>
      </li>
    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Java <sup class="new">Early Look</sup></h2>
    <ul>
          <li><a href="../overview.html">Overview</a></li>
    <li><a href="../runtime.html">Servlet Environment</a></li>
    <li><a href="index.html">Storing Data</a>
      <ul>
            <li><a href="overview.html">Overview</a></li>
    <li><a href="usingjdo.html">Using JDO</a></li>
    <li><a href="dataclasses.html">Defining Data Classes</a></li>
    <li><a href="creatinggettinganddeletingdata.html">Creating, Getting and Deleting Data</a></li>
    <li><a href="queriesandindexes.html">Queries and Indexes</a></li>
    <li><a href="transactions.html">Transactions</a></li>
    <li><a href="relationships.html">Relationships</a></li>
    <li><a href="usingjpa.html">Using JPA</a></li>
    <li><a href="../javadoc/com/google/appengine/api/datastore/package-summary.html">Low-level API</a></li>

      </ul>
    </li>
    <li><a href="../apis.html">Services</a>
      <ul>
        <li><a href="../memcache/index.html">Memcache</a>
          <ul>
                <li><a href="../memcache/overview.html">Overview</a></li>
    <li><a href="../memcache/usingjcache.html">Using JCache</a></li>
    <li><a href="../javadoc/com/google/appengine/api/memcache/package-summary.html">Low-level API</a></li>

          </ul>
        </li>
        <li><a href="../urlfetch/index.html">URL Fetch</a>
          <ul>
                <li><a href="../urlfetch/overview.html">Overview</a></li>
    <li><a href="../urlfetch/usingjavanet.html">Using java.net</a></li>
    <li><a href="../javadoc/com/google/appengine/api/urlfetch/package-summary.html">Low-level API</a></li>

          </ul>
        </li>
        <li><a href="../mail/index.html">Mail</a>
          <ul>
                <li><a href="../mail/overview.html">Overview</a></li>
    <li><a href="../mail/usingjavamail.html">Using JavaMail</a></li>
    <li><a href="../javadoc/com/google/appengine/api/mail/package-summary.html">Low-level API</a></li>

          </ul>
        </li>
        <li><a href="../images/index.html">Images</a>
          <ul>
                <li><a href="../images/overview.html">Overview</a></li>
    <li><a href="../javadoc/com/google/appengine/api/images/package-summary.html">API Reference</a></li>

          </ul>
        </li>
        <li><a href="../users/index.html">Google Accounts</a>
          <ul>
                <li><a href="../users/overview.html">Overview</a></li>
    <li><a href="../javadoc/com/google/appengine/api/users/package-summary.html">API Reference</a></li>

          </ul>
        </li>
      </ul>
    </li>
    <li><a href="../javadoc/index.html">Javadoc Reference</a></li>
    <li><a href="../jrewhitelist.html">JRE Class White List</a></li>
    <li><a href="../config/index.html">Configuration</a>
      <ul>
            <li><a href="../config/webxml.html">Deployment Descriptor</a></li>
    <li><a href="../config/appconfig.html">App Config</a></li>
    <li><a href="../config/indexconfig.html">Index Config</a></li>
    <li><a href="../config/cron.html">Scheduled Tasks</a></li>

      </ul>
    </li>
    <li><a href="../tools/index.html">Tools</a>
      <ul>
            <li><a href="../tools/devserver.html">Development Server</a></li>
    <li><a href="../tools/uploadinganapp.html">Uploading and Managing</a></li>
    <li><a href="../tools/eclipse.html">Google Plugin for Eclipse</a></li>
    <li><a href="../tools/ant.html">Using Apache Ant</a></li>

      </ul>
    </li>
    <li><a href="../howto/index.html">How-To</a>
      <ul>
              <li><a href="../howto/unittesting.html">Unit Testing</a></li>

      </ul>
    </li>

    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Python</h2>
    <ul>
          <li><a href="../../python/overview.html">Overview</a></li>
    <li><a href="../../python/runtime.html">CGI Environment</a></li>
    <li><a href="../../python/datastore/index.html">Storing Data</a>
      <ul>
             <li><a href="../../python/datastore/overview.html">Overview</a></li>
     <li><a href="../../python/datastore/entitiesandmodels.html">Entities and Models</a></li>
     <li><a href="../../python/datastore/creatinggettinganddeletingdata.html">Creating, Getting and Deleting Data</a></li>
     <li><a href="../../python/datastore/keysandentitygroups.html">Keys and Entity Groups</a></li>
     <li><a href="../../python/datastore/queriesandindexes.html">Queries and Indexes</a></li>
     <li><a href="../../python/datastore/transactions.html">Transactions</a></li>
     <li><a href="../../python/datastore/typesandpropertyclasses.html">Types and Property Classes</a></li>
     <li><a href="../../python/datastore/gqlreference.html">GQL Reference</a></li>

     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/datastore/modelclass.html">Model</a></li>
         <li><a href="../../python/datastore/expandoclass.html">Expando</a></li>
         <li><a href="../../python/datastore/polymodelclass.html">PolyModel</a></li>
         <li><a href="../../python/datastore/propertyclass.html">Property</a></li>
         <li><a href="../../python/datastore/queryclass.html">Query</a></li>
         <li><a href="../../python/datastore/gqlqueryclass.html">GqlQuery</a></li>
         <li><a href="../../python/datastore/keyclass.html">Key</a></li>
         <li><a href="../../python/datastore/functions.html">Functions</a></li>
         <li><a href="../../python/datastore/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

      </ul>
    </li>
    <li><a href="../../python/apis.html">Services</a>
      <ul>
        <li><a href="../../python/memcache/index.html">Memcache</a>
          <ul>
                 <li><a href="../../python/memcache/overview.html">Overview</a></li>
      <li><a href="../../python/memcache/usingmemcache.html">Using Memcache</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/memcache/clientclass.html">Client</a></li>
         <li><a href="../../python/memcache/functions.html">Functions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../../python/urlfetch/index.html">URL Fetch</a>
          <ul>
                 <li><a href="../../python/urlfetch/overview.html">Overview</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/urlfetch/fetchfunction.html">The fetch Function</a></li>
         <li><a href="../../python/urlfetch/responseobjects.html">Response Objects</a></li>
         <li><a href="../../python/urlfetch/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../../python/mail/index.html">Mail</a>
          <ul>
                 <li><a href="../../python/mail/overview.html">Overview</a></li>
     <li><a href="../../python/mail/sendingmail.html">Sending Mail</a></li>
     <li><a href="../../python/mail/attachments.html">Attachments</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/mail/emailmessageclass.html">EmailMessage</a></li>
         <li><a href="../../python/mail/emailmessagefields.html">Message Fields</a></li>
         <li><a href="../../python/mail/functions.html">Functions</a></li>
         <li><a href="../../python/mail/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../../python/images/index.html">Images</a>
          <ul>
                 <li><a href="../../python/images/overview.html">Overview</a></li>
     <li><a href="../../python/images/installingPIL.html">Installing PIL</a></li>
     <li><a href="../../python/images/usingimages.html">Using the Images API</a></li>
     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/images/imageclass.html">Image</a></li>
         <li><a href="../../python/images/functions.html">Functions</a></li>
         <li><a href="../../python/images/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
        <li><a href="../../python/users/index.html">Google Accounts</a>
          <ul>
                 <li><a href="../../python/users/overview.html">Overview</a></li>
     <li><a href="../../python/users/userobjects.html">User Objects</a></li>
     <li><a href="../../python/users/loginurls.html">Login URLs</a></li>
     <li><a href="../../python/users/adminusers.html">Admin Users</a></li>

     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/users/userclass.html">User</a></li>
         <li><a href="../../python/users/functions.html">Functions</a></li>
         <li><a href="../../python/users/exceptions.html">Exceptions</a></li>
       </ul>
     </li>

          </ul>
        </li>
      </ul>
    </li>
    <li><a href="../../python/config/index.html">Configuration</a>
      <ul>
            <li><a href="../../python/config/appconfig.html">App Config</a></li>
    <li><a href="../../python/config/indexconfig.html">Index Config</a></li>
    <li><a href="../../python/config/cron.html">Scheduled Tasks</a></li>

      </ul>
    </li>
    <li><a href="../../python/tools/index.html">Tools</a>
      <ul>
            <li><a href="../../python/tools/devserver.html">Development Server</a></li>
    <li><a href="../../python/tools/uploadinganapp.html">Uploading and Managing</a></li>
    <li><a href="../../python/tools/uploadingdata.html">Uploading Data</a></li>
    <li><a href="../../python/tools/webapp/index.html">webapp Framework</a>
      <ul>
             <li><a href="../../python/tools/webapp/overview.html">Overview</a></li>
     <li><a href="../../python/tools/webapp/running.html">Running the Application</a></li>
     <li><a href="../../python/tools/webapp/requesthandlers.html">Request Handlers</a></li>
     <li><a href="../../python/tools/webapp/requestdata.html">Request Data</a></li>
     <li><a href="../../python/tools/webapp/buildingtheresponse.html">Building the Response</a></li>
     <li><a href="../../python/tools/webapp/redirects.html">Redirects, Headers and Status Codes</a></li>
     

     <li><span class="tlw-title tlw-expanded">Reference</span>
       <ul>
         <li><a href="../../python/tools/webapp/requestclass.html">Request</a></li>
         <li><a href="../../python/tools/webapp/responseclass.html">Response</a></li>
         <li><a href="../../python/tools/webapp/requesthandlerclass.html">RequestHandler</a></li>
         <li><a href="../../python/tools/webapp/wsgiapplicationclass.html">WSGIApplication</a></li>
         <li><a href="../../python/tools/webapp/utilmodule.html">Utility Functions</a></li>
         
       </ul>
     </li>

      </ul>
    </li>
    <li><a href="../../python/tools/libraries.html">Third-party Libraries</a></li>

      </ul>
    </li>
    <li><a href="../../python/howto/index.html">How-To</a>
      <ul>
              <li><a href="../../python/howto/usinggdataservices.html">Google Data Services</a></li>

      </ul>
    </li>

    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Managing Your App</h2>
    <ul>
      <li><a href="../../theadminconsole.html">The Admin Console</a></li>
      <li><a href="../../quotas.html">Quotas</a></li>
      <li><a href="../../billing.html">Billing</a></li>
    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><h2>Resources</h2>
    <ul>
      <li><a href="../../../kb/index.html">FAQ</a></li>
      <li><a href="../../../articles/index.html">Articles</a></li>
      <li><a href="http://appengine-cookbook.appspot.com/">Cookbook</a></li>
      <li><a href="http://appgallery.appspot.com/">App Gallery</a></li>
      <li><a href="http://code.google.com/p/googleappengine/">SDK Code</a></li>
      <li><a href="http://code.google.com/p/google-app-engine-samples/">Sample Apps Code</a></li>
      <li><a href="../../../community.html">Discussion Groups</a></li>
    </ul>
  </li>
</ul>
<div class="line"></div>
<ul>
  <li><a href="../../roadmap.html">Product Roadmap</a></li>
  <li><a href="http://code.google.com/p/googleappengine/wiki/SdkReleaseNotes">Release Notes</a></li>
  <li><a href="../../revision_history.html">Revision History</a></li>
</ul>

        <a class="hidden" href="#gc-topnav-anchor">More Google App Engine resource links</a>
      </div>

      <div class="g-unit" id="gc-pagecontent">
        <h1 class="page_title">Defining Data Classes</h1>



<p>You can use JDO to store plain Java data objects (sometimes referred to as "Plain Old Java Objects" or "POJOs") in the datastore.  Each object that is made persistent with the PersistenceManager becomes an entity in the datastore.  You use annotations to tell JDO how to store and recreate instances of your data classes.</p>

<p class="notee"><b>Note:</b> Earlier versions of JDO use <code>.jdo</code> XML files instead of Java annotations.  These still work with JDO 2.3.  This documentation only covers using Java annotations with data classes.</p>

<ul>
  <li><a href="#Class_and_Field_Annotations">Class and Field Annotations</a></li>
  <li><a href="#Core_Value_Types">Core Value Types</a></li>
  <li><a href="#Serializable_Objects">Serializable Objects</a></li>
  <li><a href="#Child_Objects_and_Relationships">Child Objects and Relationships</a></li>
  <li><a href="#Embedded_Classes">Embedded Classes</a></li>
  <li><a href="#Collections">Collections</a></li>
  <li><a href="#Object_Fields_and_Entity_Properties">Object Fields and Entity Properties</a></li>
</ul>


<h2 id="Class_and_Field_Annotations">Class and Field Annotations</h2>

<p>Each object saved by JDO becomes an entity in the App Engine datastore.  The entity's kind is derived from the simple name of the class (inner classes use the <code>$</code> path without the package name).  Each persistent field of the class represents a property of the entity, with the name of the property equal to the name of the field (with case preserved).</p>

<p>To declare a Java class as capable of being stored and retrieved from the datastore with JDO, give the class a <code>@PersistenceCapable</code> annotation.  For example:</p>

<pre class="prettyprint">
import javax.jdo.annotations.IdentityType;
import javax.jdo.annotations.PersistenceCapable;

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class Employee {
    // ...
}
</pre>

<p>Fields of the data class that are to be stored in the datastore must be declared as persistent fields.  To declare a field as persistent, give it a <code>@Persistent</code> annotation:</p>

<pre class="prettyprint">
import java.util.Date;
import javax.jdo.annotations.Persistent;

// ...
    @Persistent
    private Date hireDate;
</pre>

<p>To declare a field as not persistent (it does not get stored in the datastore, and is not restored when the object is retrieved), give it a <code>@NotPersistent</code> annotation.</p>

<p class="note"><b>Tip:</b> JDO specifies that fields of certain types are persistent by default if neither the <code>@Persistent</code> nor <code>@NotPersistent</code> annotations are specified, and fields of all other types are not persistent by default.  See <a href="http://www.datanucleus.org/products/accessplatform_1_1/jdo/types.html">the DataNucleus documentation</a> for a complete description of this behavior.  Because not all of the App Engine datastore core value types are persistent by default according to the JDO specification, we recommend explicitly annotating fields as <code>@Persistent</code> or <code>@NotPersistent</code> to make it clear.</p>

<p>The type of a field can be any of the following.  These are described in detail below.</p>

<ul>
  <li>one of the core types supported by the datastore</li>
  <li>a Collection (such as a <code>java.util.List&lt;...&gt;</code>) or an array of values of a core datastore type</li>
  <li>an instance or Collection of instances of a <code>@PersistenceCapable</code> class</li>
  <li>an instance or Collection of instances of a Serializable class</li>
  <li>an embedded class, stored as properties on the entity</li>
</ul>

<p>A data class must have one field dedicated to storing the primary key of the corresponding datastore entity.  You can choose between 4 different kinds of key fields, each using a different value type and annotations.  (See <a href="creatinggettinganddeletingdata.html#Keys">Creating Data: Keys</a> for more information.)  The simplest key field is a long integer value that is automatically populated by JDO with a value unique across all other instances of the class when the object is saved to the datastore for the first time.  Long integer keys use a <code>@PrimaryKey</code> annotation, and a <code>@Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)</code> annotation:</p>

<p class="note"><b>Tip:</b> Make all of your persistent fields <code>private</code> or <code>protected</code> (or package protected), and only provide public access through accessor methods.  Direct access to a persistent field from another class may bypass the JDO class enhancement.  Alternatively, you can make other classes <code>@PersistenceAware</code>.  See <a href="http://www.datanucleus.org/products/accessplatform/bytecode_enhancement.html">the DataNucleus documentation</a> for more information.</p>

<pre class="prettyprint">
import javax.jdo.annotations.IdGeneratorStrategy;
import javax.jdo.annotations.PrimaryKey;

// ...
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    private Long id;
</pre>

<p>Here is an example data class:</p>

<pre class="prettyprint">
import java.util.Date;
import javax.jdo.annotations.IdGeneratorStrategy;
import javax.jdo.annotations.IdentityType;
import javax.jdo.annotations.PersistenceCapable;
import javax.jdo.annotations.Persistent;
import javax.jdo.annotations.PrimaryKey;

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class Employee {
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    private Long id;

    @Persistent
    private String firstName;

    @Persistent
    private String lastName;

    @Persistent
    private Date hireDate;

    public Employee(String firstName, String lastName, Date hireDate) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.hireDate = hireDate;
    }

    // Accessors for the fields.  JDO doesn't use these, but your application does.

    public Long getId() {
        return id;
    }

    public String getFirstName() {
        return firstName;
    } 
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    } 

    public String getLastName() {
        return lastName;
    } 
    public void setLastName(String lastName) {
        this.lastName = lastName;
    } 

    public String getHireDate() {
        return hireDate;
    } 
    public void setHireDate(Date hireDate) {
        this.hireDate = hireDate;
    } 
}
</pre>


<h2 id="Core_Value_Types">Core Value Types</h2>

<p>The datastore supports the following core value types:</p>

<table>
  <tr>
    <th>Type</th>
    <th>Java class</th>
    <th>Sort order</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>short text string, &lt; 500 bytes</td>
    <td><code>java.lang.String</code></td>
    <td>Unicode</td>
    <td>A value longer than 500 bytes throws a JDOFatalUserException.</td>
  </tr>
  <tr>
    <td>short byte string, &lt; 500 bytes</td>
    <td><code>com.google.appengine.api.datastore.ShortBlob</code></td>
    <td>byte order</td>
    <td>A value longer than 500 bytes throws a JDOFatalUserException.</td>
  </tr>
  <tr>
    <td>Boolean value</td>
    <td><code>boolean</code> or <code>java.lang.Boolean</code></td>
    <td><code>false</code> &lt; <code>true</code></td>
    <td></td>
  </tr>
  <tr>
    <td>integer</td>
    <td><code>short</code>, <code>java.lang.Short</code>, <code>int</code>, <code>java.lang.Integer</code>, <code>long</code>, <code>java.lang.Long</code></td>
    <td>Numeric</td>
    <td>Stored as long integer, then converted to the field type.  Out-of-range values overflow.</td>
  </tr>
  <tr>
    <td>floating point number</td>
    <td><code>float</code>, <code>java.lang.Float</code>, <code>double</code>, <code>java.lang.Double</code></td>
    <td>Numeric</td>
    <td>Stored as double-width float, then converted to the field type.  Out-of-range values overflow.</td>
  </tr>
  <tr>
    <td>date-time</td>
    <td><code>java.util.Date</code></td>
    <td>Chronological</td>
    <td></td>
  </tr>
  <tr>
    <td>Google account</td>
    <td><code>com.google.appengine.api.users.User</code></td>
    <td>By email address (Unicode)</td>
    <td></td>
  </tr>
  <tr>
    <td>long text string</td>
    <td><code>com.google.appengine.api.datastore.Text</code></td>
    <td>(not orderable)</td>
    <td>Not indexed.</td>
  </tr>
  <tr>
    <td>long byte string</td>
    <td><code>com.google.appengine.api.datastore.Blob</code></td>
    <td>(not orderable)</td>
    <td>Not indexed.</td>
  </tr>
  <tr>
    <td>entity key</td>
    <td><code>com.google.appengine.api.datastore.Key</code>, or the referenced object (as a child)</td>
    <td>By path elements (kind, ID or name, kind, ID or name...)</td>
    <td></td>
  </tr>
  <tr>
    <td>a URL</td>
    <td><code>com.google.appengine.api.datastore.Link</code></td>
    <td>Unicode</td>
    <td></td>
  </tr>
</table>

<p class="note"><b>Note:</b> The datastore supports several additional core value types that are not yet implemented in the Java datastore API, but are implemented in the Python API.  If a property has a value with any of these types and the entity is loaded into an object with a field for the property, JDO will behave as if the property does not exist: it will set the field to <code>null</code> or throw a NullPointerException if the field type is non-nullable.  The unsupported types are: Category, Email, IM, PhoneNumber, PostalAddress, Rating, GeoPt.</p>

<p>To represent a property containing a single value of a core type, declare a field of the Java type, and use the <code>@Persistent</code> annotation:</p>

<pre class="prettyprint">
import java.util.Date;
import javax.jdo.annotations.Persistent;

// ...
    @Persistent
    private Date hireDate;
</pre>


<h2 id="Serializable_Objects">Serializable Objects</h2>

<p>A field value can contain an instance of a Serializable class, storing the serialized value of the instance in a single property value of the type Blob.  To tell JDO to serialize the value, the field uses the annotation <code>@Persistent(serialized=true)</code>.  Blob values are not indexed and cannot be used in query filters or sort orders.</p>

<p>Here is an example of a simple Serializable class that represents a file, including the file contents, a filename and a MIME type.  This is not a JDO data class, so there are no persistence annotations.</p>

<pre class="prettyprint">
import java.io.Serializable;

public class DownloadableFile implements Serializable {
    private byte[] content;
    private String filename;
    private String mimeType;

    // ... accessors ...
}
</pre>

<p>To store an instance of a Serializable class as a Blob value in a property, declare a field whose type is the class, and use the <code>@Persistent(serialized = "true")</code> annotation:</p>

<pre class="prettyprint">
import javax.jdo.annotations.Persistent;
import DownloadableFile;

// ...
    @Persistent(serialized = "true")
    private DownloadableFile file;
</pre>


<h2 id="Child_Objects_and_Relationships">Child Objects and Relationships</h2>

<p>A field value that is an instance of a <code>@PersistenceCapable</code> class creates an owned one-to-one relationship between two objects.  A field that is a collection of such references creates an owned one-to-many relationship.</p>

<p><b>Important:</b> Owned relationships have implications for transactions, entity groups, and cascading deletes.  See <a href="transactions.html">Transactions</a> and <a href="relationships.html">Relationships</a> for more information.</p>

<p>Here is a simple example of an owned one-to-one relationship between an Employee object and a ContactInfo object:</p>

<p><b><code>ContactInfo.java</code></b></p>
<pre class="prettyprint">
import com.google.appengine.api.datastore.Key;
// ... imports ...

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class ContactInfo {
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    private Key key;

    @Persistent
    private String streetAddress;

    @Persistent
    private String city;

    @Persistent
    private String stateOrProvince;

    @Persistent
    private String zipCode;

    // ... accessors ...
}
</pre>

<p><b><code>Employee.java</code></b></p>
<pre class="prettyprint">
import ContactInfo;
// ... imports ...

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class Employee {
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    private Long id;

    @Persistent
    private ContactInfo myContactInfo;

    // ... accessors ...
}
</pre>

<p>In this example, if the app creates an Employee instance, populates its <code>myContactInfo</code> field with a new ContactInfo instance, then saves the Employee instance with <code>pm.makePersistent(...)</code>, the datastore creates two entities.  One is of the kind <code>"ContactInfo"</code>, representing the ContactInfo instance.  The other is of the kind <code>"Employee"</code>.  The key of the <code>ContactInfo</code> entity has the key of the <code>Employee</code> entity as its entity group parent.</p>


<h2 id="Embedded_Classes">Embedded Classes</h2>

<p>Embedded classes allow you to model a field value using a class without creating a new datastore entity and forming a relationship.  The fields of the object value are stored directly in the datastore entity for the containing object.</p> 

<p>Any <code>@PersistenceCapable</code> data class can be used as an embedded object in another data class.  The class's <code>@Persistent</code> fields are embedded in the object.  If you give the class to embed the <code>@EmbeddedOnly</code> annotation, the class can only be used as an embedded class.  The embedded class does not need a primary key field because it is not stored as a separate entity.</p>

<p>Here is an example of an embedded class.  This example makes the embedded class an inner class of the data class that uses it; this is useful, but not required to make a class embeddable.</p>

<pre class="prettyprint">
import javax.jdo.annotations.Embedded;
import javax.jdo.annotations.EmbeddedOnly;
// ... imports ...

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class EmployeeContacts {
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    Long id;
    
    @PersistenceCapable
    @EmbeddedOnly
    public static class ContactInfo {
        @Persistent
        private String streetAddress;

        @Persistent
        private String city;

        @Persistent
        private String stateOrProvince;

        @Persistent
        private String zipCode;

        // ... accessors ...
    }

    @Persistent
    @Embedded
    private ContactInfo homeContactInfo;
}
</pre>

<p>The fields of an embedded class are stored as properties on the entity, using the name of each field and the name of the corresponding property.  If you have more than one field on the object whose type is an embedded class, you must rename the fields of one so they do not conflict with another.  You specify new field names using arguments to the <code>@Embedded</code> annotation.  For example:</p>

<pre class="prettyprint">
    @Persistent
    @Embedded
    private ContactInfo homeContactInfo;

    @Persistent
    @Embedded(members = {
        @Persistent(name="streetAddress", columns=@Column(name="workStreetAddress")),
        @Persistent(name="city", columns=@Column(name="workCity")),
        @Persistent(name="stateOrProvince", columns=@Column(name="workStateOrProvince")),
        @Persistent(name="zipCode", columns=@Column(name="workZipCode")),
    })
    private ContactInfo workContactInfo;
</pre>

<p>Similarly, fields on the object must not use names that collide with fields of embedded classes, unless the embedded fields are renamed.</p>

<p>Because the embedded class's persistent properties are stored on the same entity as the other fields, you can use persistent fields of the embedded class in JDOQL query filters and sort orders.  You can refer to the embedded field using the name of the outer field, a dot (<code>.</code>), and the name of the embedded field.  This works whether or not the property names for the embedded fields have been changed using <code>@Column</code> annotations.</p>

<pre>
    select from EmployeeContacts where workContactInfo.zipCode == "98105"
</pre>


<h2 id="Collections">Collections</h2>

<p>A datastore property can have more than one value.  In JDO, this is represented by a single field with a Collection type, where the collection is of one of the core value types or a Serializable class.  The following Collection types are supported:</p>

<ul>
  <li><code>java.util.ArrayList&lt;...&gt;</code></li>
  <li><code>java.util.HashSet&lt;...&gt;</code></li>
  <li><code>java.util.LinkedHashSet&lt;...&gt;</code></li>
  <li><code>java.util.LinkedList&lt;...&gt;</code></li>
  <li><code>java.util.List&lt;...&gt;</code></li>
  <li><code>java.util.Set&lt;...&gt;</code></li>
  <li><code>java.util.SortedSet&lt;...&gt;</code></li>
  <li><code>java.util.Stack&lt;...&gt;</code></li>
  <li><code>java.util.TreeSet&lt;...&gt;</code></li>
  <li><code>java.util.Vector&lt;...&gt;</code></li>
</ul>

<p>If a field is declared as a List, objects returned by the datastore will have an ArrayList value.  If a field is declared as a Set, the datastore returns a HashSet.  If a field is declared as a SortedSet, the datastore returns a TreeSet.</p>

<p>For example, a field whose type is <code>List&lt;String&gt;</code> is stored as zero or more string values for the property, one for each value in the <code>List</code>.</p>

<pre class="prettyprint">
import java.util.List;
// ... imports ...

// ...
    @Persistent
    List&lt;String&gt; favoriteFoods;
</pre>

<p>A Collection of child objects (of <code>@PersistenceCapable</code> classes) creates multiple entities with a one-to-many relationship.  See <a href="relationships.html">Relationships</a>.</p>

<p>Datastore properties with more than one value have special behavior for query filters and sort orders.  See <a href="queriesandindexes.html">Queries and Indexes: Sort Orders and Properties With Multiple Values</a> for more information.</p>


<h2 id="Object_Fields_and_Entity_Properties">Object Fields and Entity Properties</h2>

<p>The App Engine datastore makes a distinction between an entity without a given property and an entity with a <code>null</code> value for a property.  JDO does not support this distinction: every field of an object has a value, possibly <code>null</code>.  If a field with a nullable value type (something other than a built-in type like <code>int</code> or <code>boolean</code>) is set to <code>null</code>, when the object is saved, the resulting entity will have the property set with a null value.</p>

<p>If a datastore entity is loaded into an object and doesn't have a property for one of the object's fields and the field's type is a nullable single-value type, the field is set to <code>null</code>.  When the object is saved back to the datastore, the <code>null</code> property becomes set in the datastore to the null value.  If the field is not of a nullable value type, loading an entity without the corresponding property throws an exception.  This won't happen if the entity was created from the same JDO class used to recreate the instance, but can happen if the JDO class changes, or if the entity was created using the low-level API instead of JDO.</p>

<p>If a field's type is a Collection of a core data type or a Serializable class and there are no values for the property on the entity, the empty collection is represented in the datastore by setting the property to a single null value.  If the field's type is an array type, it is assigned an array of 0 elements.  If the object is loaded and there is no value for the property, the field is assigned an empty collection of the appropriate type.  Internally, the datastore knows the difference between an empty collection and a collection containing one null value.</p>

<p>If the entity has a property that does not have a corresponding field in the object, that property is inaccessible from the object.  If the object is saved back to the datastore, the extra property is deleted.</p>

<p>If an entity has a property whose value is of a different type than the corresponding field in the object, JDO attempts to cast the value to the field type.  If the value cannot be cast to the field type, JDO throws a ClassCastException.  In the case of numbers (long integers and double-width floats), the value is converted, not cast.  If the numeric property value is larger than the field type, the conversion overflows without throwing an exception.</p>



      </div><!-- end gc-pagecontent -->
   </div><!-- end gooey wrapper -->

    </div> <!-- end codesite content -->

<div id="gc-footer" dir="ltr">
  <div class="text">
    
      <div class="notice"><div id="notice" style="text-align: center; border: 1em 0em 1em 0em">
  Except as otherwise <a
  href="http://code.google.com/policies.html#restrictions">noted</a>,
  the content of this page is licensed under the <a rel="license"
  href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
  Attribution 2.5 License</a>, and code samples are licensed under the
  <a rel="license" href="http://www.apache.org/licenses/LICENSE-2.0">Apache
  2.0 License</a>.
<!-- <rdf:RDF xmlns="http://web.resource.org/cc/" 
              xmlns:dc="http://purl.org/dc/elements/1.1/"
              xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  <Work rdf:about="">
    <license rdf:resource="http://creativecommons.org/licenses/by/2.5/" />
  </Work>
  <License rdf:about="http://creativecommons.org/licenses/by/2.5/">
    <permits rdf:resource="http://web.resource.org/cc/Reproduction"/>
    <permits rdf:resource="http://web.resource.org/cc/Distribution"/>
    <requires rdf:resource="http://web.resource.org/cc/Notice"/>
    <requires rdf:resource="http://web.resource.org/cc/Attribution"/>
    <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/>
  </License>
</rdf:RDF> -->
</div>
Java is a registered trademark of Sun Microsystems, Inc.</div>
    
    &copy;2009 Google -
    <a href="http://code.google.com">Code Home</a> -
    <a href="http://www.google.com/accounts/TOS">Terms of Service</a> -
    <a href="http://www.google.com/privacy.html">Privacy Policy</a> -
    <a href="http://code.google.com/more">Site Directory</a>
    <br /> <br />
    Google Code offered in:
    <a href="http://code.google.com/intl/en">English</a> -
    <a href="http://code.google.com/intl/es">Español</a> -
    <a href="http://code.google.com/intl/ja">日本語</a> -
    <a href="http://code.google.com/intl/ko">한국어</a> -
    <a href="http://code.google.com/intl/pt-BR">Português</a> -
    <a href="http://code.google.com/intl/ru">Pусский</a> -
    <a href="http://code.google.com/intl/zh-CN">中文(简体)</a> -
    <a href="http://code.google.com/intl/zh-TW">中文(繁體)</a>
  </div>
</div><!-- end gc-footer -->

</div><!-- end gc-containter -->

<script type="text/javascript">CODESITE_CSITimer['load'].tick('ats');</script>
<script src="../../../../js/codesite_tail.pack.04102009.js" type="text/javascript"></script>






  </body>
</html>


